Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| JavaTM 2 Platform Std. Ed. v1.4.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## javax.imageio.spi
Class ServiceRegistry

    java.lang.Object
      |
      +--javax.imageio.spi.ServiceRegistry

Direct Known Subclasses:
  IIORegistry

public class ServiceRegistry
extends Object

A registry for service provider instances.

A service is a well-known set of interfaces and (usually abstract) classes. A service provider is a specific implementation of a service. The classes in a provider typically implement the interface or subclass the class defined by the service itself.

Service providers are stored in one or more categories, each of which is defined by a class of interface (described by a `Class` object) that all of its members must implement. The set of categories may be changed dynamically.

Only a single instance of a given leaf class (that is, the actual class returned by `getClass()`, as opposed to any inherited classes or interfaces) may be registered. That is, suppose that the `com.mycompany.mypkg.GreenServiceProvider` class implements the `com.mycompany.mypkg.MyService` interface. If a `GreenServiceProvider` instance is registered, it will be stored in the category defined by the `MyService` class. If a new instance of `GreenServiceProvider` is registered, it will replace the previous instance. In practice, service provider objects are usually singletons so this behavior is appropriate.

To declare a service provider, a `services` subdirectory is placed within the `META-INF` directory that is present in every JAR file. This directory contains a file for each service provider interface that has one or more implementation classes present in the JAR file. For example, if the JAR file contained a class named `com.mycompany.mypkg.MyServiceImpl` which implements the `javax.someapi.SomeService` interface, the JAR file would contain a file named:

     META-INF/services/javax.someapi.SomeService

containing the line:

     com.mycompany.mypkg.MyService

The service provider classes should be to be lightweight and quick to load. Implementations of these interfaces should avoid complex dependencies on other classes and on native code. The usual pattern for more complex services is to register a lightweight proxy for the heavyweight service.

An application may customize the contents of a registry as it sees fit, so long as it has the appropriate runtime permission.

For more details on declaring service providers, and the JAR format in general, see the JAR File Specification.

See Also:
  `RegisterableService`

Nested Class Summary
`static interface` | `ServiceRegistry.Filter` A simple filter interface used by `ServiceRegistry.getServiceProviders` to select providers matching an arbitrary criterion.

Constructor Summary
`ServiceRegistry(Iterator categories)` Constructs a `ServiceRegistry` instance with a set of categories taken from the `categories` argument.

Method Summary
`boolean` | `contains(Object provider)` Returns `true` if `provider` is currently registered.
`void` | `deregisterAll()` Deregisters all currently registered service providers from all categories.
`void` | `deregisterAll(Class category)` Deregisters all service provider object currently registered under the given category.
`void` | `deregisterServiceProvider(Object provider)` Removes a service provider object from all categories that contain it.
`boolean` | `deregisterServiceProvider(Object provider, Class category)` Removes a service provider object from the given category.
`void` | `finalize()` Finalizes this object prior to garbage collection.
`Iterator` | `getCategories()` Returns an `Iterator` of `Class` objects indicating the current set of categories.
`Object` | `getServiceProviderByClass(Class providerClass)` Returns the currently registered service provider object that is of the given class type.
`Iterator` | `getServiceProviders(Class category, boolean useOrdering)` Returns an `Iterator` containing all registered service providers in the given category.
`Iterator` | `getServiceProviders(Class category, ServiceRegistry.Filter filter, boolean useOrdering)` Returns an `Iterator` containing service provider objects within a given category that satisfy a criterion imposed by the supplied `ServiceRegistry.Filter` object's `filter` method.
`static Iterator` | `lookupProviders(Class providerClass)` Locates and incrementally instantiates the available providers of a given service using the context class loader.
`static Iterator` | `lookupProviders(Class providerClass, ClassLoader loader)` Searches for implementations of a particular service class using the given class loader.
`void` | `registerServiceProvider(Object provider)` Adds a service provider object to the registry.
`boolean` | `registerServiceProvider(Object provider, Class category)` Adds a service provider object to the registry.
`void` | `registerServiceProviders(Iterator providers)` Adds a set of service provider objects, taken from an `Iterator` to the registry.
`boolean` | `setOrdering(Class category, Object firstProvider, Object secondProvider)` Sets a pairwise ordering between two service provider objects within a given category.
`boolean` | `unsetOrdering(Class category, Object firstProvider, Object secondProvider)` Sets a pairwise ordering between two service provider objects within a given category.

Methods inherited from class java.lang.Object
`clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### ServiceRegistry

    public ServiceRegistry(Iterator categories)

  Constructs a `ServiceRegistry` instance with a set of categories taken from the `categories` argument.

Parameters:
  `categories` - an `Iterator` containing `Class` objects to be used to define categories.
Throws:
  `IllegalArgumentException` - if `categories` is `null`.

Method Detail

### lookupProviders

    public static Iterator lookupProviders(Class providerClass,
                                           ClassLoader loader)

  Searches for implementations of a particular service class using the given class loader.

  This method transforms the name of the given service class into a provider-configuration filename as described in the class comment and then uses the `getResources` method of the given class loader to find all available files with that name. These files are then read and parsed to produce a list of provider-class names. The iterator that is returned uses the given class loader to look up and then instantiate each element of the list.

  Because it is possible for extensions to be installed into a running Java virtual machine, this method may return different results each time it is invoked.

  Parameters:
    `providerClass` - a `Class`object indicating the class or interface of the service providers being detected.
    `loader` - the class loader to be used to load provider-configuration files and instantiate provider classes, or `null` if the system class loader (or, failing that the bootstrap class loader) is to be used.
  Returns:
    An `Iterator` that yields provider objects for the given service, in some arbitrary order. The iterator will throw an `Error` if a provider-configuration file violates the specified format or if a provider class cannot be found and instantiated.
  Throws:
    `IllegalArgumentException` - if `providerClass` is `null`.

### lookupProviders

    public static Iterator lookupProviders(Class providerClass)

  Locates and incrementally instantiates the available providers of a given service using the context class loader. This convenience method is equivalent to:

         ClassLoader cl = Thread.currentThread().getContextClassLoader();
         return Service.providers(service, cl);

  Parameters:
    `providerClass` - a `Class`object indicating the class or interface of the service providers being detected.
  Returns:
    An `Iterator` that yields provider objects for the given service, in some arbitrary order. The iterator will throw an `Error` if a provider-configuration file violates the specified format or if a provider class cannot be found and instantiated.
  Throws:
    `IllegalArgumentException` - if `providerClass` is `null`.

### getCategories

    public Iterator getCategories()

  Returns an `Iterator` of `Class` objects indicating the current set of categories. The iterator will be empty if no categories exist.

  Returns:
    an `Iterator` containing `Class`objects.

### registerServiceProvider

    public boolean registerServiceProvider(Object provider,
                                           Class category)

  Adds a service provider object to the registry. The provider is associated with the given category.

  If `provider` implements the `RegisterableService` interface, its `onRegistration` method will be called. Its `onDeregistration` method will be called each time it is deregistered from a category, for example if a category is removed or the registry is garbage collected.

  Parameters:
    `provider` - the service provide object to be registered.
    `category` - the category under which to register the provider.
  Returns:
    true if no provider of the same class was previously registered in the same category category.
  Throws:
    `IllegalArgumentException` - if `provider` is `null`.
    `ClassCastException` - if provider does not implement the `Class` defined by `category`.

### registerServiceProvider

    public void registerServiceProvider(Object provider)

  Adds a service provider object to the registry. The provider is associated within each category present in the registry whose `Class` it implements.

  If `provider` implements the `RegisterableService` interface, its `onRegistration` method will be called once for each category it is registered under. Its `onDeregistration` method will be called each time it is deregistered from a category or when the registry is finalized.

  Parameters:
    `provider` - the service provider object to be registered.
  Throws:
    `IllegalArgumentException` - if `provider` is `null`.

### registerServiceProviders

    public void registerServiceProviders(Iterator providers)

  Adds a set of service provider objects, taken from an `Iterator` to the registry. Each provider is associated within each category present in the registry whose `Class` it implements.

  For each entry of `providers` that implements the `RegisterableService` interface, its `onRegistration` method will be called once for each category it is registered under. Its `onDeregistration` method will be called each time it is deregistered from a category or when the registry is finalized.

  Parameters:
    `providers` - an Iterator containing service provider objects to be registered.
  Throws:
    `IllegalArgumentException` - if `providers` is `null` or contains a `null` entry.

### deregisterServiceProvider

    public boolean deregisterServiceProvider(Object provider,
                                             Class category)

  Removes a service provider object from the given category. If the provider was not previously registered, nothing happens and `false` is returned. Otherwise, `true` is returned. If an object of the same class as `provider` but not equal (using `==`) to `provider` is registered, it will not be deregistered.

  If `provider` implements the `RegisterableService` interface, its `onDeregistration` method will be called.

  Parameters:
    `provider` - the service provider object to be deregistered.
    `category` - the category from which to deregister the provider.
  Returns:
    `true` if the provider was previously registered in the same category category, `false` otherwise.
  Throws:
    `IllegalArgumentException` - if `provider` is `null`.
    `ClassCastException` - if provider does not implement the class defined by `category`.

### deregisterServiceProvider

    public void deregisterServiceProvider(Object provider)

  Removes a service provider object from all categories that contain it.

  Parameters:
    `provider` - the service provider object to be deregistered.
  Throws:
    `IllegalArgumentException` - if `provider` is `null`.

### contains

    public boolean contains(Object provider)

  Returns `true` if `provider` is currently registered.

  Parameters:
    `provider` - the service provider object to be queried.
  Returns:
    `true` if the given provider has been registered.
  Throws:
    `IllegalArgumentException` - if `provider` is `null`.

### getServiceProviders

    public Iterator getServiceProviders(Class category,
                                        boolean useOrdering)

  Returns an `Iterator` containing all registered service providers in the given category. If `useOrdering` is `false`, the iterator will return all of the server provider objects in an arbitrary order. Otherwise, the ordering will respect any pairwise orderings that have been set. If the graph of pairwise orderings contains cycles, any providers that belong to a cycle will not be returned.

  Parameters:
    `category` - the category to be retrieved from.
    `useOrdering` - `true` if pairwise orderings should be taken account in ordering the returned objects.
  Returns:
    an `Iterator` containing service provider objects from the given category, possibly in order.
  Throws:
    `IllegalArgumentException` - if there is no category corresponding to `category`.

### getServiceProviders

    public Iterator getServiceProviders(Class category,
                                        ServiceRegistry.Filter filter,
                                        boolean useOrdering)

  Returns an `Iterator` containing service provider objects within a given category that satisfy a criterion imposed by the supplied `ServiceRegistry.Filter` object's `filter` method.

  The `useOrdering` argument controls the ordering of the results using the same rules as `getServiceProviders(Class, boolean)`.

  Parameters:
    `category` - the category to be retrieved from.
    `filter` - an instance of `ServiceRegistry.Filter` whose `filter` method will be invoked.
    `useOrdering` - `true` if pairwise orderings should be taken account in ordering the returned objects.
  Returns:
    an `Iterator` containing service provider objects from the given category, possibly in order.
  Throws:
    `IllegalArgumentException` - if there is no category corresponding to `category`.

### getServiceProviderByClass

    public Object getServiceProviderByClass(Class providerClass)

  Returns the currently registered service provider object that is of the given class type. At most one object of a given class is allowed to be registered at any given time. If no registered object has the desired class type, `null` is returned.

  Parameters:
    `providerClass` - the `Class` of the desired service provider object.
  Returns:
    a currently registered service provider object with the desired `Class`type, or `null` is none is present.
  Throws:
    `IllegalArgumentException` - if `providerClass` is `null`.

### setOrdering

    public boolean setOrdering(Class category,
                               Object firstProvider,
                               Object secondProvider)

  Sets a pairwise ordering between two service provider objects within a given category. If one or both objects are not currently registered within the given category, or if the desired ordering is already set, nothing happens and `false` is returned. If the providers previously were ordered in the reverse direction, that ordering is removed.

  The ordering will be used by the `getServiceProviders` methods when their `useOrdering` argument is `true`.

  Parameters:
    `category` - a `Class` object indicating the category under which the preference is to be established.
    `firstProvider` - the preferred provider.
    `secondProvider` - the provider to which `firstProvider` is preferred.
  Returns:
    `true` if a previously unset ordering was established.
  Throws:
    `IllegalArgumentException` - if either provider is `null` or they are the same object.

### unsetOrdering

    public boolean unsetOrdering(Class category,
                                 Object firstProvider,
                                 Object secondProvider)

  Sets a pairwise ordering between two service provider objects within a given category. If one or both objects are not currently registered within the given category, or if no ordering is currently set between them, nothing happens and `false` is returned.

  The ordering will be used by the `getServiceProviders` methods when their `useOrdering` argument is `true`.

  Parameters:
    `category` - a `Class` object indicating the category under which the preference is to be disestablished.
    `firstProvider` - the formerly preferred provider.
    `secondProvider` - the provider to which `firstProvider` was formerly preferred.
  Returns:
    `true` if a previously set ordering was disestablished.
  Throws:
    `IllegalArgumentException` - if either provider is `null` or they are the same object.

### deregisterAll

    public void deregisterAll(Class category)

  Deregisters all service provider object currently registered under the given category.

  Parameters:
    `category` - the category to be emptied.
  Throws:
    `IllegalArgumentException` - if there is no category corresponding to `category`.

### deregisterAll

    public void deregisterAll()

  Deregisters all currently registered service providers from all categories.

### finalize

    public void finalize()
                  throws Throwable

  Finalizes this object prior to garbage collection. The `deregisterAll` method is called to deregister all currently registered service providers. This method should not be called from application code.

  Overrides:
    `finalize` in class `Object`
  Throws:
    `Throwable` - if an error occurs during superclass finalization.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| JavaTM 2 Platform Std. Ed. v1.4.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Submit a bug or feature
For further API reference and developer documentation, see Java 2 SDK SE Developer Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.

Java, Java 2D, and JDBC are trademarks or registered trademarks of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2002 Sun Microsystems, Inc. 901 San Antonio Road
Palo Alto, California, 94303, U.S.A. All Rights Reserved.